/**
*  \file    segfile.h
*
*  \brief   Header for the 'segfile' unit, which is used to interpret segmentation files.
*
*  \author  <ralf.huber@linde-mh.de>
*/

#ifndef SEGFILE_H_INCLUDED
#define SEGFILE_H_INCLUDED

#ifndef SEGFILE_LINKAGE
#define SEGFILE_LINKAGE extern
#endif

/*================================================[ public includes  ]================================================*/
#include "../cfg/prj.h"
#include "../sections/sections.h"

/*================================================[ public defines   ]================================================*/

/*================================================[ public datatypes ]================================================*/
typedef struct segfile segfile_t;

/*================================================[ public variables ]================================================*/

/*================================================[ public functions ]================================================*/
/* Opens a segmentation file, checks if its content is valid and reads the content into an internal buffer. The segments
 * defined in the segmentation file can then be obtained by calling 'segfile_get_sections'.
 *
 * \param   fileName Path of the segmentation file.
 * \return  A pointer to an internal structure which represents the segmentation file.\n
 *          NULL if an error occured.
 */
segfile_t* segfile_open(const char* const fileName);

/**
 * This function returns the sections that have been found in the segmentation file.
 *
 * \param   segfile     A structure obtained from 'segfile_open'.
 * \return  Pointer to a section_list which contains the sections found in the segmentation file.
 */
struct section_list* segfile_get_sections(const segfile_t* const segfile);

/**
 * This function returns the path to the segmentation file which was used to open it using 'segfile_open'.
 *
 * \param   segfile     A structure obtained from 'segfile_open'.
 * \return  Pointer to a section_list which contains the sections found in the segmentation file.
 */
const char* segfile_get_filename(const segfile_t* const segfile);

/**
 * This function frees the memory which has been allocated during a call to 'segfile_open' and invalidates the
 * corresponding segfile_t structure.
 *
 * \param   segfile     A structure obtained from 'segfile_open'.
 */
void segfile_close(segfile_t* segfile);

/*====================================================================================================================*/

#endif

/***********************************************************************************************************************
*                             Copyright 2013 Linde Material Handling. All rights reserved.                             *
***********************************************************************************************************************/
